The Vehicle API is a RESTful web service that enables Verizon Connect Reveal customers to integrate 3rd party back-office systems with REVEAL to keep driver, user, vehicle, and group information up to date.
The Vehicle API is separated out into different services that have a variety of methods that can be accessed to create, update, and delete key objects within a REVEAL account.
This documentation will breakdown each of the services and the methods that are available: Drivers, Users, Vehicles, and Groups.
Key concepts for using the Vehicle API methods:
Vehicle API is offered as a RESTful web service
Standard REST verbs are applied: GET, POST, PUT, DELETE
Vehicle API services: Drivers, Users, Vehicles, and Groups
Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created, updated, or deleted. The unique identifiers are as follows and can be managed within the REVEAL account by the same field name.
o Vehicles = Vehicle Number
o Groups = Group ID
Note: To return information on Non-powered assets please call for the methods specified in Non-Powered Assets API
The returned response will be restricted to the Reveal account's data plan. If the information being queried is outside of the data plan, a "400 Bad Request error "response will be returned.
For more details on your account's data plan please reach out to Verizon Connect Customer Support
Vehicles marked as hidden in the Reveal will not return via the Vehicle API
|
API Name |
Vehicle- Vehicles |
|
Endpoint |
|
|
Operation |
GET and PUT Note: Users do not have the ability to CREATE vehicles within their REVEAL account. For every GPS tracking unit purchased and installed, a vehicle record will be created within the user s account to be updated with relevant details within REVEAL s Admin section or through the use of a PUT method. Additionally, users cannot DELETE vehicles within an account through REVEAL or the API. |
The GET Vehicle methods enable integration users to retrieve Vehicle data by calling for all vehicles within an account or a specific vehicle at a time.
The GET Vehicles method provides integration users with the ability to retrieve a list of vehicles with additional meta data.
|
Operation and Path |
GET https://fim.api.us.fleetmatics.com/cmd/v1/vehicles HTTP/1.1 |
|
HOST |
fim.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token]
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
[
{
"Name": "FD 0339",
"VehicleNumber": "33901",
"RegistrationNumber": null,
"VIN": null,
"Make": "FORD",
"Year": 2010,
"Model": "ECONOLINE",
"TankCapacity": null,
"HighwayMPG": null,
"CityMPG": null,
"VehicleSize": 0,
"HasNavigationDevice": true,
"FuelType": 1,
"HasTachograph": false
"VehicleId": 1
},
The GET Vehicle by Vehicle Number method enables the integration user to specify the vehicle to be retrieved.
|
Operation and Path |
GET https://fim.api.us.fleetmatics.com/cmd/v1/vehicles?=<VehicleNumber> HTTP/1.1 |
|
HOST |
fim.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token]
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"Name": "FD 0339",
"VehicleNumber": "33901",
"RegistrationNumber": null,
"VIN": null,
"Make": "FORD",
"Year": 2010,
"Model": "ECONOLINE",
"TankCapacity": 113.562353673961,
"HighwayMPG": 6.72042,
"CityMPG": 11.76073,
"VehicleSize": 0,
"HasNavigationDevice": true,
"FuelType": 1,
"HasTachograph": false
"VehicleId": 1
}
The GET Vehicle by Vehicle Ids method enables the integration user to specify the vehicles to be retrieved (one or multiple).
|
Operation and Path |
GET https://fim.api.eu.fleetmatics.com/cmd/v1/vehicles?vehicleids=<VehicleId>,<VehicleId> HTTP/1.1 |
|
HOST |
fim.api.eu.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token]
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"Name": "FD 0339",
"VehicleNumber": "33901",
"RegistrationNumber": null,
"VIN": null,
"Make": "FORD",
"Year": 2010,
"Model": "ECONOLINE",
"TankCapacity": 113.562353673961,
"HighwayMPG": 6.72042,
"CityMPG": 11.76073,
"VehicleSize": 0,
"HasNavigationDevice": true,
"FuelType": 1,
"HasTachograph": false,
"VehicleId": 1
}
|
Field |
JSON Formatted Sample |
Field Notes and Default Values |
|
Name |
[ { "Name": "FD 0339",
|
The Vehicle Name as recorded within the REVEAL vehicle profile. |
|
Vehicle Number |
"VehicleNumber": "33901", |
The Vehicle Number is the unique identifier that will be used to reference the vehicle within the API. The Vehicle Number is not a mandatory field within the REVEAL account, but is required for the API. |
|
Registration Number |
"RegistrationNumber": null, |
Registration Number is not a required field within the REVEAL vehicle profile. When the Registration value is provided it will be required to be unique within an account. |
|
VIN |
"VIN": null,
|
Vehicle Identification Number, the unique serial code provided by the automotive manufacturer for the vehicle. |
|
Make |
"Make": "FORD", |
The vehicle manufacturer s brand. |
|
Year |
"Year": 2010,
|
The year the vehicle was manufactured. |
|
Model |
"Model": "ECONOLINE",
|
The type of vehicle by the manufacturer. |
|
Tank Capacity |
"TankCapacity": null, |
Tank Capacity should be provided and referenced in liters. Tank Capacity is not a required field but a key element when using Fuel Card features. |
|
Highway MPG |
"HighwayMPG": null,
|
Highway MPG is an estimated value provided by the customer. The value should be provided and referenced in liters. Highway MPG is not a required field but a key element when using Fuel Card features. |
|
City MPG |
"CityMPG": null, |
City MPG is an estimated value provided by the customer. The value should be provided and referenced in liters. City MPG is not a required field but a key element when using Fuel Card features. |
|
Vehicle Size |
"VehicleSize": 0 },
|
Vehicle Size refers to the vehicle s classification of Light-Duty, Medium-Duty, or Heavy-Duty. When setting this value via the API, the following values should be referenced: 0: Light Duty 1: Medium Duty 2: Heavy Duty The vehicle s size will automatically default to Light Duty. |
|
Has Navigation Device |
"HasNavigationDevice": "" |
Has Navigation Device is a Boolean field for true or false. This indicates whether the vehicle has a Garmin navigation device installed. |
|
Fuel Type |
"FuelType": 1, |
The Fuel Type of the vehicle. Returns as 0,1 or 2 where 0-Unleaded, 1 -Diesel, and 2 -Battery Electric Vehicle. |
|
Vehicle Id |
"VehicleId": 1, |
This is an integer that serves as a primary key, uniquely identifying each record in the table. |
|
Has Tachograph |
"HasTachograph": false |
Has Tachograph is a Boolean field for true or false. This indicates whether the vehicle has a tachograph device installed. |
The GET Vehicles by Group ID method provides integration users with the ability to retrieve all vehicles associated with the Group ID. Results will include Vehicle Number and other relevant vehicle details. Multiple vehicles can be returned for each Group ID provided as groups can contain multiple vehicles within REVEAL.
|
Operation and Path |
GET https://fim.api.us.fleetmatics/cmd/v1/vehicles/group?={GroupID} HTTP/1.1 |
|
HOST |
https://fim.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere realm=http://atmosphere,atmosphere_app_id=<Integration Manager App ID>, Bearer <token> Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls |
[
{
"Name": "Ed's Car - 4641114658",
"VehicleNumber": "4641114658",
"RegistrationNumber": "RegNumber 196213",
"ESN": "890001"
"FuelType": 1
},
{
"Name": "Ed's Car - 4641063665",
"VehicleNumber": "4641063665",
"RegistrationNumber": "RegNumber 196214",
"ESN": "890002"
"FuelType": 1
}
]
|
Field |
JSON Formatted Sample |
Field Notes and Default Values |
|
Name |
{ "Name": "", |
The Vehicle Name as recorded within the REVEAL vehicle profile. |
|
Vehicle Number |
"VehicleNumber": "",
|
The Vehicle Number is the unique identifier within the API. The Vehicle Number is not a mandatory field within the REVEAL account, but is required for the API. |
|
Registration Number |
"RegistrationNumber": "",
|
Registration Number is not a required field within the REVEAL profile. When the Registration value is provided it will be required to be unique within the account. |
|
ESN |
"ESN : "", |
ESN is used to uniquely identify a vehicle from another. It is a mandatory field for vehicle creation in Reveal. |
|
Fuel Type |
"FuelType : "", |
The Fuel Type of the vehicle. Returns as 0,1 or 2 where 0-Unleaded, 1 -Diesel, and 2 -Battery Electric Vehicle. |
PUT Vehicle by Vehicle Number is a method to update the vehicle s profile details. Vehicles must already be assigned a unique Vehicle Number in order to update via the API.
{
"Name":"Vehicle 1",
"RegistrationNumber":"44046",
"VehicleNumber":"890001",
"VehicleSize":"12",
"FuelType": 1,
}
|
Operation and Path |
PUT https://fim.api.us.fleetmatics.com/cmd/v1/vehicles/<VehicleNumber> HTTP/1.1 |
|
HOST |
fim.api.us.fleetmatics.com |
|
Content-Type |
application/json |
|
Accept |
application/json |
|
Content-Length |
This value will auto-generate based on the body of the request. |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token]
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
Successfully edited vehicles will return a 200 code
Unfound Vehicle Numbers, or the unique identifier used for the call, will return a 404 error
Bad requests, typically due to an error in the call s content, will return a 400 error
Invalid tokens or an Authorization problem will return a 401 error
If the service is unavailable at the time the call was made a 500 error will return
PUT Odometer by Vehicle Number is a method to update a vehicle s current odometer or odometer as of x date. A vehicle s odometer can be backdated 30 days from the updated date and time.
The value s to be provided within the request s body should include the Odometer as reference in kilometers and the As Of date and timestamp.
{
"Odometer": 47569,
"AsOf": "2016-09-01T00:00:00"
}
|
Operation and Path |
PUT https://fim.api.us.fleetmatics.com/cmd/v1/vehicles/<VehicleNumber>/odometer HTTP/1.1 |
|
HOST |
fim.api.us.fleetmatics.com |
|
Content-Type |
application/json |
|
Accept |
application/json |
|
Content-Length |
This value will auto-generate based on the body of the request. |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token]
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
PUT methods will not return an object review. The response will be limited to a set of standard HTTP codes:
Successfully edited vehicles will return a 200 code
Unfound Vehicle Numbers, or the unique identifier used for the call, will return a 404 error
Bad requests, typically due to an error in the call s content, will return a 400 error
o Bad requests can include when the user provides an As Of value greater than 30 days
Invalid tokens or an Authorization problem will return a 401 error
If the service is unavailable at the time the call was made a 500 error will return
PUT Hours of Use by Vehicle Number is a method to update a vehicle s current hours of use as of x date. A vehicle s hours of use can be backdated up 30 days from the updated date and time.
The value s to be provided within the request s body should include the Minutes of Use and the As Of date and timestamp.
{
"MinutesOfUse": 6050,
"AsOf": "2016-09-09T00:00:00"
}
|
Operation and Path |
PUT https://fim.api.us.fleetmatics.com/cmd/v1/vehicles/<VehicleNumber> HTTP/1.1 |
|
HOST |
fim.api.us.fleetmatics.com |
|
Content-Type |
application/json |
|
Accept |
application/json |
|
Content-Length |
This value will auto-generate based on the body of the request. |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token]
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
PUT methods will not return an object review. The response will be limited to a set of standard HTTP codes:
Successfully edited vehicles will return a 200 code
Unfound Vehicle Numbers, or the unique identifier used for the call, will return a 404 error
Bad requests, typically due to an error in the call s content, will return a 400 error
o Bad requests can include when the user provides an As Of value greater than 30 days
Invalid tokens or an Authorization problem will return a 401 error
If the service is unavailable at the time the call was made a 500 error will return
PUT Primary Group by Vehicle Number is a method for updating a vehicle s primary group. If the Vehicle Number is currently assigned to a primary group, the vehicle will update to reflect the Group ID provided.
The value to be provided within the request s body should include Group ID that corresponds to the Primary Group that the vehicle number is being added to.
{
"PrimaryGroupId":"12345"
}
Note: The PrimaryGroupId value is the Group ID that is the unique identifier assigned when creating and modifying groups within REVEAL s Admin section. The Group ID is not a mandatory field within REVEAL but is required for invoking group based APIs.
|
Operation and Path |
PUT https://fim.api.us.fleetmatics.com/cmd/v1/groups/vehicles/<VehicleNumber> HTTP/1.1 |
|
HOST |
fim.api.us.fleetmatics.com |
|
Content-Type |
application/json |
|
Accept |
application/json |
|
Content-Length |
This value will auto-generate based on the body of the request. |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token]
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
PUT methods will not return an object review. The response will be limited to a set of standard HTTP codes:
Successfully edited vehicles will return a 200 code
Unfound Vehicle Numbers, or the unique identifier used for the call, will return a 404 error
Bad requests, typically due to an error in the call s content, will return a 400 error
Invalid tokens or an Authorization problem will return a 401 error
If the service is unavailable at the time the call was made a 500 error will return